Mac Magazin/MacEasy 14/Mac Magazin and MacEasy Magazine CD - Issue 14.iso/Wissenschaft & Technik/Tools Plus 2.6.1 Evaluation Kit/Tools Plus 2.6.1/User Manual/09-Editing Fields (2 of 2)

INI File | 1994-09-17 | 25KB | 335 lines

[Display using Monaco 9]


NewStrHandle
````````````
Allocate memory for a Pascal string, and initialize it to an empty string.

   pascal StringHandle NewStrHandle (short StringLen);

   function NewStrHandle (StringLen: INTEGER): STRINGHANDLE;

  StringLen is the size of the Pascal string (from 1 to 255 characters) being allocated.  NewStrHandle automatically allocates one additional byte of heap memory to accommodate the entire Pascal string plus a length byte.

  The function’s value returns a string handle to a Pascal string of the specified length.  The string is initialized to an empty string (‘’), thus making is ready for immediate use with the NewField or NewFieldRect routines.

------------------------------------------------------------------------

NewField
````````
Create a new field.  The new field is not activated.

   pascal void NewField (short Field, short left, short top,
                 short right, short bottom,
                 Handle hStr, short teType, short Just);

   procedure NewField(Field, left, top, right, bottom: INTEGER;
                 hStr: HANDLE; teType, Just: INTEGER);

  Field specifies the field number (from 1 to 255) that is created in the current window.  Once a field is created, it is referenced by this field number.  If a field has been previously created in the current window using the same number, it is replaced with a new field as specified by the parameters in the NewField procedure.  If the current window doesn’t belong to your application, or if no windows are open, NewField does nothing.

  Left, top, right, and bottom define a rectangle in local co-ordinates that determines the field’s size and location in the current window.  These parameters can be seen as two corners; the upper left-hand corner (left,top) and the bottom right-hand corner (right,bottom).  The field must be wide enough for at least 1 character (minimum of 20 pixels).  The height of the field should be the same as a font’s height (font height can be determined by calling the GetFontInfo procedure and adding Ascent + Descent + Leading ).  In multiple-line fields, the height should be in increments of the font height.

  HStr is a handle that provides this field with a reference to its string.  The handle can be generic, but it’s treated like a string handle by Tools Plus, in that the first byte of its memory block is a length byte and the remainder is the actual string.  A copy of the hStr handle’s contents is used while the field is being edited.  It is also used to automatically display an inactive edit field’s text when a window needs to be refreshed.  Each field must have its own string.  You must allocate memory for the handle and set it to a default string value before using it in the NewField routine.  A good way to both allocate and initialize the handle is to use the NewStrHandle routine.

  TeType indicates two things: [1] if Return is allowed in a field, and [2] if a box is drawn around the field.  If Return is allowed, typing the Return key creates a new line in the field.  If Return is not allowed, it generates a doKeyDown or doAutoKey event and is handled by your application.  In this case, Return may be treated the same way as Tab.  If a box is drawn around the field, it is drawn as a line that is 1 pixel wide, and is exactly 3 pixels larger than the dimensions specified by left, top, right, and bottom.  This complies with the boxes seen around fields in dialog boxes.  One reason you may decide not to have a box drawn around your field is to accommodate a large number of small fields in a window.  Constants have been defined for this purpose and are listed at the end of this section.

  Just specifies if a field is left aligned, right aligned, or centered.  See the relevant constants at the end of this section.




Fonts
`````
  When a field is created, the window’s current font, size and style settings (as set by the TextFont, TextSize, and TextFace procedures) are remembered by the field.  The window’s settings can then be changed without affecting the field.  The field’s font, size, and style cannot be changed without recreating the field.


Single Line Fields
``````````````````
Tools Plus lets you create single line editing fields in which word wrap does not occur, and characters are automatically scrolled horizontally along a single line.  To create a single line field, set the field’s height equal to its font’s height (font height can be determined by calling the GetFontInfo procedure and adding Ascent + Descent + Leading).  You must also specify a teType that disallows carriage returns (either teBoxNoCR or teNoBoxNoCR).

  Also see:  NewFieldRect, and the FieldLengthLimit procedure to limit the length of editable text.


Note: Tools Plus makes no attempt to control the placement of fields or
      to protect them once they have been created.  It is the
      programmer’s responsibility to ensure that fields are a sufficient
      size (at least 1 character wide and high), and that their
      placement within the window is reasonable and does not conflict
      with other objects.  Furthermore, you should not allow your
      application’s text and drawing processes to interfere with fields.
      Windows with a “size box” should not allow fields to be obscured
      or hidden by making the window too small.

Warning: Your application must allocate memory for each handle that it
         provides to NewField by using the NewHandle routine.  Tools
         Plus does not automatically allocate this memory.  If your
         editing fields contain random characters, it is a sure sign
         that you have not allocated memory for your handle.


  CONST                   {Field types                            }
    teBoxNoCR   = 0       {Outlining box is drawn, Return is not  }
                          {  allowed (default)                    }
    teBoxCR     = 1       {Outlining box is drawn, Return is      }
                          {  allowed                              }
    teNoBoxNoCR = 2       {No outlining box, Return is not allowed}
    teNoBoxCR   = 3       {No outlining box, Return is allowed    }
                          {Text alignment                         }
    teJustLeft  = 0       {Left aligned (default)                 }
    teJustCenter= 1       {Centered                               }
    teJustRight =-1       {Right aligned                          }

------------------------------------------------------------------------

NewFieldRect
````````````
Create a new field.  The new field is not activated.

   pascal void NewFieldRect (short Field, Rect *Bounds, Handle hStr,
                 short teType, short Just);

   procedure NewFieldRect(Field: INTEGER; Bounds: RECT; hStr: HANDLE;
                 teType, Just: INTEGER);

  NewFieldRect is identical to the NewField procedure, except that it accepts the Bounds rectangle in place of the individual left, top, right and bottom co-ordinates.

------------------------------------------------------------------------

DeleteField
```````````
Delete a field.

   pascal void DeleteField (short Field);

   procedure DeleteField(Field: INTEGER);

  Field specifies the field number (from 1 to 255) that is deleted from the current window.  If the current window doesn’t belong to your application, or if no windows are open, or if the field does not exist in the current window, DeleteField does nothing.

  If the field being deleted is the active field then it is deactivated before being deleted.  If field was also in an active, modeless window, the Edit menu’s “Undo” item is changed to “Can’t Undo” and is disabled along with the “Cut”, “Copy”, “Paste” and “Clear” items.

------------------------------------------------------------------------

ActivateField
`````````````
Activate a field.

   pascal void ActivateField (short Field, short Selection);

   procedure ActivateField(Field, Selection: INTEGER);

  Field specifies the field number (from 1 to 255) being activated in the current window.  If the current window doesn’t belong to your application, or if no windows are open, or if the field does not exist in the current window, ActivateField does nothing.  If another field is active in the same window when ActivateField is called, the previously active field is deactivated before the target field is activated.

  Selection specifies if the field is left-aligned, right-aligned, or centered.  Single line fields that are left or right aligned don’t not use “word wrap.”  Instead, the field’s text scrolls to keep the selection in view.  The three constants that can be used to specify a field’s text selection are teSelectStart, teSelectEnd, and teSelectAll.

  If the field being activated is in an active, modeless window, the Edit menu’s “Undo” item is changed to “Can’t Undo” and is disabled, while the “Cut”, “Copy”, “Paste” and “Clear” items are enabled/disabled according to the insertion point or selection (as previously described in this chapter under “The Edit Menu”).

  Your application can activate a field in a tool bar or floating palette only if the user is already working in an active field on that window.  The user starts working in a tool bar’s or palette’s field (subject to approval by your application) by clicking or double-clicking in the target field.  Once the user starts working in a tool bar’s or floating palette’s editing field (by clicking in it), your application can activate other fields in the same window by using ActivateField.  The most common example of this is when the user tabs to the next field or Shift-Tabs to the previous one.

  CONST                   {Field text selection                   }
    teSelectAll  =0;      {Select all the field’s text            }
    teSelectStart=1;      {Insertion point at beginning of field  }
    teSelectEnd  =2;      {Insertion point at end of field        }

------------------------------------------------------------------------

DeactivateField
```````````````
Deactivate the active field.

   pascal void DeactivateField(void);

   procedure DeactivateField;

  The active field, if one exists in the current window, is deactivated by this routine.  If the current window doesn’t belong to your application, or if no windows are open, or if a field is not active, DeactivateField does nothing.  Once a field is deactivated, its edited text is discarded and replaced with the field’s string.  Therefore, if you want to save the field’s edited text, call GetFieldString and SaveFieldString prior to deactivating the field.

  If the deactivated field is in an active, modeless window, the Edit menu’s “Undo” item is changed to “Can’t Undo” and is disabled along with the “Cut”, “Copy”, “Paste” and “Clear” items.

------------------------------------------------------------------------

ClickInField
````````````
Process a mouse click that has occurred in an inactive field on the active window.

   pascal void ClickInField(void);

   procedure ClickInField;

  When PollSystem reports a doClickField event, it indicates that the user clicked the mouse in an inactive field.  If some other field is active when this event is reported, it is necessary to first process the active field before responding to the click (before ClickInField is called).  First, call GetFieldString to retrieve the active field’s edited text for validation.  If the string cannot be validated, display an appropriate alert box and ignore the doClickField event.  If no error occurred, save the edited text as the field’s string by calling SaveFieldString, then process the click by calling ClickInField.

  ClickInField deactivates any active field, and activates the field in which the click occurred by placing an insertion point at the click’s location.  A double click in the field and/or subsequent dragging is processed automatically as detailed by “Clicking and Tabbing in Fields” earlier in this chapter.

  If the activated field is in a modeless window, the Edit menu’s “Undo” item is changed to “Can’t Undo” and is disabled, while the “Cut”, “Copy”, “Paste” and “Clear” items are enabled/disabled as previously described in this chapter under “The Edit Menu”.

Warning: Between the time when the doClickField event is reported and
         when ClickInField is called, observe the following rules:
            • do not call PollSystem
            • do not open or close any windows, including alerts and
              dialogs
            • do not hide or show any windows
            • do not activate any windows
         ClickInField depends on working with the same window that
         registered the doClickField event, and will not function
         properly if PollSystem reports or processes any subsequent
         events.

------------------------------------------------------------------------

GetFieldString
``````````````
Obtain a copy of the active field’s edited text.

   pascal void GetFieldString (Str255 EditString);

   procedure GetFieldString(var EditString: Str255);

  EditString is a copy of the edited text from your application’s active field.  If your application doesn’t have an active field, GetFieldString tries to retrieve the active field’s edited text from the current window.  The field’s edited text and string are not changed.  Although it is physically possible to type more than 255 characters in a field that is not length limited, only the first 255 characters are significant.  The rest are ignored.  If the current window doesn’t belong to your application or if it doesn’t have an “active” field, or if no windows are open, GetFieldString returns a null string (string length of 0).

  If the field is not length limited, the text retrieved by GetFieldString may be greater in length than the field’s associated string (as specified by the hStr handle when the field was created).  If the field is length limited, EditString’s length will never exceed the size limit of the field’s associated string.

  GetFieldString is necessary when validating a field’s edited text.  For example, if a doKeyDown even reports that the Tab key was pressed, the active field should be validated before activating the next field.  GetFieldString obtains a copy of the edited text and allows your application to validate the field.  If the field cannot be validated, an appropriate alert should be displayed and the doKeyDown event should be ignored.  If the field is successfully validated, the edited text should be saved as the field’s associated string by calling the SaveFieldString procedure, then the next field should be activated.

------------------------------------------------------------------------

SaveFieldString
```````````````
Save the active field’s edited text as the field’s associated string.

   pascal void SaveFieldString(void);

   procedure SaveFieldString;

  SaveFieldString takes a copy of your application’s active field’s edited text and copies it to the field’s associated string.  If your application doesn’t have an active editing field, this action occurs in the current window.  The field’s edited text is not changed.  If the current window doesn’t belong to your application, or if no windows are open, or if a field is not active, SaveFieldString does nothing.

  When SaveFieldString is called, several factors determine the length of the string, or number of characters that are saved.  Firstly, only the first 255 characters of the edited text are recognized.  The rest are ignored.  Secondly, the active field’s string handle (hStr) dictates the maximum number of characters that can be saved.  The edited text is saved as a string in the memory block dereferenced by hStr.  The maximum string length will always be an even number, with the exception of a Str255 type that is 255 characters long.  If the field is length limited, the edited text will comply to these constraints by physically preventing the user from typing characters that would exceed the field’s limit.

------------------------------------------------------------------------

EditFldWindowNumber
```````````````````
Get the window number of the window containing your application’s active editing field.

   pascal short EditFldWindowNumber(void);

   function EditFldWindowNumber: INTEGER;

  This function returns a window pointer to a Tools Plus window regardless if it is open or not.

  This function returns the window number of the window containing the active editing field in your application.  If your application does not have a tool bar or floating palettes, this window will either be the active window (front most), or it will be zero (0) when there is no active field or no windows are open.  When a tool bar and/or floating palettes are used, this window can potentially be any of the active windows (tool bar, any floating palette, or the active standard window).

------------------------------------------------------------------------

ActiveFieldNumber
`````````````````
Determine the active field number.

   pascal short ActiveFieldNumber(void);

   function ActiveFieldNumber: INTEGER;

  The function’s value returns the active field number in the current window.  If the current window does not belong to your application, or if no windows are open, or if no field is active in the current window, ActiveFieldNumber returns a value of zero (0).  If you want to determine which window contains your application’s active field, use the EditFldWindowNumber routine.

------------------------------------------------------------------------

FieldIsEmpty
````````````
Determine if the specified field is empty.

   pascal Boolean FieldIsEmpty (short Field);

   function FieldIsEmpty (Field: INTEGER): BOOLEAN;

  Field specifies the field number (from 1 to 255) that is queried in the current window.

  The function’s value returns true if the field is empty (string length is zero).  A non-zero length string returns a value of false.  If the specified field is the window’s active editing field (even though the window itself may not be active at the time), the function is performed on the field’s edited text.  Otherwise, the function is performed on the field’s string.  If the current window doesn’t belong to your application, or if no windows are open, or if the field does not exist in the current window, FieldIsEmpty returns with a value of true.

------------------------------------------------------------------------

FieldLengthLimit
````````````````
Turn field length limiting on or off.

   pascal void FieldLengthLimit (Boolean Limits);

   procedure FieldLengthLimit(Limit: BOOLEAN);

  Limit specifies if subsequently created fields are length limited or not.  The boolean constants “on” or “off” may be used.

  Length limiting is an enhancement supported by Tools Plus.  It prevents a field’s edited text from exceeding a fixed length.  This is done by preventing additional characters from being typed once the field has reached its limit, and by truncating text (if necessary) after a “Paste” command is executed.  The user is beeped when excess characters are typed instead of accepting the key-strokes.

  If a field is length limited, the limit is set to the maximum length of the field’s string (referenced via the hStr handle) as described in the NewField procedure.

  A field takes on its limited/unlimited status when it is created by the NewField procedure, depending on FieldLengthLimit’s setting.  When FieldLengthLimit(true) has been set, subsequently created fields are length limited.  When FieldLengthLimit(false) is in effect, subsequently created fields will not be length limited.

  For the sake of consistency, all fields on a window should either be limited or unlimited.  Length limiting works best, in a visual sense, when a mono-spaced (non-proportional) font is used and the field’s width is long enough to contain the maximum number of characters.  In this way, the user is limited to the number of characters that are visible in a field.

FieldLengthLimit is set to false when Tools Plus is initialized.

------------------------------------------------------------------------

OffsetField
```````````
Repositioning a field.

   pascal void OffsetField (short Field, short dh, short dv);

   procedure OffsetField(Field, dh, dv: INTEGER);

  Field specifies the field number (from 1 to 255) that is repositioned in the current window.  If the current window doesn’t belong to your application, or if no windows are open, or if the field does not exist in the current window, OffsetField does nothing.

  Dh and dv specify the horizontal and vertical number of pixels by which the field is offset.  If dh and dv are positive, the offsetting is to the right and down.  If either are negative, offsetting is in the opposite direction.

  The OffsetField procedure merely changes the field’s co-ordinates.  It does not actually redraw the field at its new location.  To do this, the field’s old location must be erased and the new location should be added to the affected window’s update region.





Scrolling fields
````````````````
  Your application can create a matrix of fields and treat them as though they were “cells” in a spread-sheet.  For example, fields could be aligned to represent columns and rows: Seven rows, each with 3 fields, is a total of 21 fields.  In fact, any combination of lines and columns can be used as long as no more than 255 fields are visible at a time.

  By scrolling up or down, the user is given the impression that there are actually more lines available than those that are currently visible.  The scrolling process is accomplished by the following series of steps.

 (1) Shift Lines: Use the toolbox’s ScrollRect procedure to shift the lines to their new position.  They should be shifted to the position where they will appear after scrolling.

 (2) Stop Window Updating: Freeze the window in its current state and prevent it from being changed.  One of the ways to do this is to store a copy of the affected window’s visRgn, then clear the visRgn with the SetEmptyRgn procedure.

 (3) Delete Old Fields: Delete fields that have been scrolled out of view.  Because the window is frozen, the DeleteField routine will not change the window.

 (4) Shift Fields: Shift each remaining field that will still be visible after scrolling.  Use OffsetField to shift the fields’ locations to their new positions.

 (5) Resume Updating Window: Restore the affected window’s visRgn.  Subsequent changes are immediately visible in the window.

 (6) Create New Fields: Create new fields that are now in view due to scrolling.

  Note that within the steps outlined above, you will have to decide how your application deals with the active field and its edited text, since it may be scrolled out of view during this process.

------------------------------------------------------------------------

PasteIntoField
``````````````
Paste text into a field on the current window.

   pascal void PasteIntoField (short Field, Str255 Text,
                 Boolean Replace);

   procedure PasteIntoField(Field: INTEGER; Text: STRING;
                 Replace: BOOLEAN);

  Some applications may require that text be pasted directly into a field under your application’s control.  An example of this may be an operation that lets the user select a commonly used item from a List Box.  The selected item could then be pasted into a field as though the user had typed it.  Use this routine judiciously, because indiscriminate pasting can be detrimental to a good user interface.  Text can be pasted into an active or inactive field.  After pasting into an active field, the insertion point is placed after the last character of the pasted text, then the Edit menu, if one exists, has its “Undo” item set to “Undo Paste,” thereby allowing the pasting to be undone.

  Field specifies the field number (from 1 to 255) into which the text is pasted in the current window.  If the current window doesn’t belong to your application, or if no windows are open, or if the field does not exist in the current window, PasteIntoField does nothing.

  Text specifies the string that is pasted into the specified field.  If a null string (length of 0) is specified, the field’s affected text is cleared.  When pasting into a length limited field, text is pasted one character at a time (although very quickly) and stops if the field is full.

  Replace specifies if the text is pasted into the field to replace the currently selected characters, or if the field’s entire contents are replaced with the specified text.  With the value of teInsert, only the selected range of characters is replaced.  If an insertion point is present, Text is inserted at that point.  If Replace has a value of teReplace, the field’s entire text is replaced with the contents of the Text string.  When pasting into an inactive field, the field’s contents are replaced regardless of the value of the Replace variable.

  CONST                   {Types of pasting                       }
    teReplace =true       {Replace field’s contents with specified}
                          {  text.                                }
    teInsert  =false      {Insert specified text at the insertion }
                          {  point.                               }

------------------------------------------------------------------------